Namespaces

Within this specification, the following namespace prefix bindings are used:

Indication of Requirement Levels

Within this document the definitions of MUST, SHOULD and MAY are used as defined in [[!rfc2119]].

Number Formatting

Within this document, decimal numbers will use a dot "." as the decimal mark.

Creating a Folder

The Data Package API provides a method to create a folder in another folder of the Data Package. The method takes the name of the new folder as argument and returns a reference to the new folder. The method throws an Exception, if a folder or file with this name already exists in the target folder. Further, the name of the folder MUST fulfil the interoperability requirements (described in [[!ADF-DP]]). Otherwise an exception is thrown.

The following example shows the creation of a folder:

JAVA:
// Retrieves the Data Package of the opened file.
DataPackage dataPackage = adfFile.getDataPackage();

// Retrieves the root folder of the DataPackage.
DpFolder rootFolder = dataPackage.openRootFolder();

// Creates a new folder "myFolder"
DpFolder newFolder = rootFolder.createFolder("myFolder");

C#:
// Retrieves the Data Package of the opened file.
DataPackage dataPackage = adfFile.getDataPackage();

// Retrieves the root folder of the DataPackage.
DpFolder rootFolder = dataPackage.openRootFolder();

// Creates a new folder "myFolder"
DpFolder newFolder = rootFolder.createFolder("myFolder");
				

The meta-data created in the triple store look like this:

<urn:uuid:6eca6e3e-0e88-4de1-a048-334e124b0f6d>
      a       af-dp:Folder , ldp:Container ;
      dc:title "myFolder"^^xsd:string ;
      af-dp:representedBy <hdf:/data-package> .

<hdf:/data-package>
      a       hdf:Group ;
      hdf:name "data-package"^^xsd:string .
				

Accessing a Folder

The ADF-DP API provides a method to access a given folder in a Data Package. The folder MAY be given by URI, by absolute path or by relative path. The method takes the name resp. the URI of the folder as argument and returns a reference to this folder, if it exists.

The method throws an exception, if the folder given by URI or by path does not exist. The folder returned by this method MUST fulfil the requirements for accessing a folder specified in [[!ADF-DP]].

JAVA:
DpFolder folder = dataPackage.getFolderByURI("urn:uuid:1123123-123123...");

C#:
DpFolder folder = dataPackage.getFolderByURI("urn:uuid:1123123-123123...");
				

JAVA:
DpFolder folder = dataPackage.getFolderByPath("/a/b/c");

C#:
DpFolder folder = dataPackage.getFolderByPath("/a/b/c");
				

JAVA:
DpFolder folder = dataPackage.openRootFolder().openFolder("a").openFolder("b").openFolder("c");
folder.getAbsolutePath(); -> /a/b/c

JAVA:
DpFolder folder = dataPackage.openRootFolder().openFolder("a").openFolder("b").openFolder("c");
folder.getAbsolutePath(); -> /a/b/c
				

Listing the Content of a Folder

The ADF-DP API provides a method to list the contents of a folder in a given Data Package. The method returns an empty list, if the folder does not have any contents.

JAVA:
DpFolder rootFolder = dataPackage.openRootFolder();

List<DpNode> contents = rootFolder.contents();
for (DpNode content : contents)
{
	if (content instanceOf DpFolder) {
		// print out the inherent meta data of the folder, e.g. content.getName(), content.getCreationOn(), ...
	} else if (content instanceOf IFile) {
		// print out the inherent meta data of the file, e.g. content.getName(), content.getSize(), ...
	}
}

C#:
DpFolder rootFolder = dataPackage.openRootFolder();

java.util.List contents = rootFolder.contents();
foreach (DpNode content in contents)
{
	if (content is DpFolder) {
		// print out the inherent meta data of the folder, e.g. content.getName(), content.getCreationOn(), ...
	} else if (content is IFile) {
		// print out the inherent meta data of the file, e.g. content.getName(), content.getSize(), ...
	}
}
				

The meta data of files and folders to load is based on the requirements for accessing files and accessing folders specified in [[!ADF-DP]].

Renaming a Folder

The ADF-DP API provides a method to rename a folder in a given Data Package:

JAVA and C#:
// Renames the folder "oldName" to "newName"
theFolder.renameTo("newName");
				

Deleting a Folder

The ADF-DP API provides a method to delete a folder in a given Data Package:

JAVA:
// Deletes the folder "toBeDeleted"
dataPackage.deleteFolder("/helloWorld/toBeDeleted");

C#:
// Deletes the folder "toBeDeleted"
dataPackage.deleteFolder("/helloWorld/toBeDeleted");
				

Creating a File

The following example demonstrates how a file is created:

JAVA:
// Retrieves the folder "helloWorld"
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");

// Creates the file "Hello World.txt" inside the "helloWorld" folder
DpFile file = helloWorld.createFile("Hello World.txt");

C#:
// Retrieves the folder "helloWorld"
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");

// Creates the file "Hello World.txt" inside the "helloWorld" folder
DpFile file = helloWorld.createFile("Hello World.txt");
				

When creating a file, a UUID URN URI is generated (file-URI) and the class of the file stated (adf-dp:File and ldp:Resource) in the ADF Triple Store:

$fileURI rdfs:type adf-dp:File, ldp:Resource.
				

<urn:uuid:fde37fc2-296a-4bbf-8f7c-219d50de2dc1>
	a      		ldp:Resource, adf-dp:File ;
	dc:title 	"fileName"^^xsd:string ;
	adf-dp:representedBy <hdf:/data-package/fileName> .

<hdf:/data-package/fileName>
	a      		hdf:Dataset ;
	hdf:name	"fileName"^^xsd:string .

Accessing a File

The ADF-DP API provides a method to access a given file in a Data Package. The file MAY be given by URI, by absolute path or by relative path (as shown in the next example). The method takes the name resp. the URI of the file as argument and returns a reference to this file, if it exists.

The method throws an exception, if the file given by URI or by path does not exist.

The file returned by this method fulfils the requirements specified in [[!ADF-DP]].

JAVA:
// Retrieves the file "Hello World.txt" directly. The name here has to be absolute!
DpFile file1 = dataPackage.openFile("/helloWorld/Hello World.txt");

C#:
// Retrieves the file "Hello World.txt" directly. The name here has to be absolute!
DpFile file1 = dataPackage.openFile("/helloWorld/Hello World.txt");

JAVA:
// Retrieves the folder "helloWorld"
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");
DpFile file1 = helloWorld.openFile("Hello World.txt");

C#:
// Retrieves the folder "helloWorld"
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");
DpFile file1 = helloWorld.openFile("Hello World.txt");

Reading a File

The ADF-DP API provides methods to read a given file in a Data Package either as byte content or as an input stream.

JAVA:
// Retrieves the file "Hello World.txt" directly.
DpFile file = dataPackage.openFile("/helloWorld/Hello World.txt");

// Reads the content of the file.
byte[] bytes = file.read();
String text = new String(bytes);

C#:
// Retrieves the file "Hello World.txt" directly.
DpFile file = dataPackage.openFile("/helloWorld/Hello World.txt");

// Reads the content of the file.
sbyte[] bytes = file.read();
String text = esme.util.StringUtil.create(bytes);
				

JAVA:
DpFile file = dataPackage.openFile("/helloWorld/streamedFile.bin");

// Creates an input stream to read from the file.
try (InputStream is1 = new DpInputStream(file))
{
	// Streaming to file
	int int1;
	while ((int1 = is1.read()) != -1)
	{
		byte byte1 = (byte) int1;
		log.info("" + byte1);
	}
}

C#:
// Creates an input stream to read from the file.
DpInputStream is1 = new DpInputStream(null);
try
{
	int int1;
	while ((int1 = is1.read()) != -1)
	{
		sbyte byte1 = (sbyte) int1;
		Log.info("" + byte1);
	}
}
finally
{
	is1.close();
}
			

Updating a File

The ADF-DP API provides a method to write bytes into a given File within a Data Package. When updating a file, the meta data of the class adf-dp:File MUST be fulfilled at modification time and updated in the ADF-TS as specified in [[!ADF-DP]].

The detailed specification for writing into a file is given in [[!ADF-DP]].

JAVA:
// Retrieves the file "Hello World.txt" directly.
DpFile file = dataPackage.openFile("/helloWorld/Hello World.txt");

// Writes new content to the file. Default is overwriting.
file.write("2, 3, 5, 7 and 11".getBytes());

// -> "2, 3, 5, 7 and 11"

C#:
// Retrieves the file "Hello World.txt" directly.
DpFile file = dataPackage.openFile("/helloWorld/Hello World.txt");

// Writes new content to the file. Default is overwriting.
file.write(esme.util.StringUtil.getBytes("2, 3, 5, 7 and 11"));

// -> "2, 3, 5, 7 and 11"
				

JAVA:
// continued from previous example
file.write(" are prime numbers".getBytes(), OpenOption.APPEND);

// -> "2, 3, 5, 7 and 11 are prime numbers"

C#:
// continued from previous example
file.write(esme.util.StringUtil.getBytes(" are prime numbers"), OpenOption.APPEND);

// -> "2, 3, 5, 7 and 11 are prime numbers"
				

JAVA:
// Retrieves the folder "helloWorld" directly.
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");

// Creates a new file to stream to.
DpFile file = helloWorld.createFile("streamedFile.bin");

int numberToWrite = 0;

// Creates an output stream to write to the new file.
try (OutputStream os = new DpOutputStream(file))
{
	while (numberToWrite < 1000)
	{
		os.write(numberToWrite++);
	}
}

C#:
// Retrieves the folder "helloWorld" directly.
DpFolder helloWorld = dataPackage.openFolder("/helloWorld");

// Creates a new file to stream to.
DpFile file = helloWorld.createFile("streamedFile.bin");

int numberToWrite = 0;

// Creates an output stream to write to the new file.
java.io.OutputStream os = new DpOutputStream(file);
try
{
	while (numberToWrite < 1000)
	{
		os.write(numberToWrite++);
	}
}
finally
{
	os.close();
}
				

JAVA and C#:
// Renames the file "oldName.txt" to "newName.txt"
theFile.renameTo("newName.txt");
				

JAVA:
// Deletes the file "toBeDeleted.txt"
dataPackage.deleteFile("/helloWorld/toBeDeleted.txt");

C#:
// Deletes the file "toBeDeleted.txt"
dataPackage.deleteFile("/helloWorld/toBeDeleted.txt");
				

Import

The import functionality imports the whole content of a folder or just a file into the ADF. It creates DpFolder and DpFile according to the hierarchy of the import content and preserves meta-data of the original files and folders. Symbolic links are automatically followed. If this behavior is not wanted, it can be turned off by org.allotrope.adf.enums.LinkOption.NOFOLLOW_LINKS.

By default files are imported as normal DpFiles with a block size of 8000 bytes. Those files can be changed and renamed like all other DpFiles. If imported with the import option org.allotrope.adf.enums.ImportOption.FIXED_SIZE the DpFiles will be stored as read-only files that use only their real size inside the ADF DataPackage.

JAVA and C#:
// import contents of system folder into ADF folder "dpFolder"
dataPackage.importIntoDpFolder(importDirectoryPath, dpFolder);

// it is also possible to just import a single file into the ADF DpFolder
dataPackage.importIntoDpFolder(anyFilePath, dpFolder);

// Symbolic links are automatically followed. If this behavior is not wanted, it can be turned off by specifying LinkOption.NOFOLLOW_LINKS
dataPackage.importIntoDpFolder(anyFilePath, dpFolder, LinkOption.NOFOLLOW_LINKS);

// Files are stored as normal DpFiles. If the size of the ADF file is important and the files will not be changed inside the ADF file, this
// can be changed by specifying ImportOption.FIXED_SIZE
dataPackage.importIntoDpFolder(anyFilePath, dpFolder, ImportOption.FIXED_SIZE);

// LinkOption.NOFOLLOW_LINKS and ImportOption.FIXED_SIZE may be used at the same time
dataPackage.importIntoDpFolder(anyFilePath, dpFolder, LinkOption.NOFOLLOW_LINKS, ImportOption.FIXED_SIZE);

		

Export

The export functionality exports the content of the ADF DpFolder or just a DpFile according to their hierarchy in the ADF to the specified system folder. Preserved meta-data is automatically restored.

JAVA and C#:
// export contents of dpFolder into system folder "exportDirectory"
dataPackage.exportDpFolder(dpFolder, exportDirectory);

// it is also possible to just export a single DpFile
dataPackage.exportDpFile(dpFile, exportDirectory);